@meissa_a/meissa 0.1.0

package/README.md

@@ -0,0 +1,350 @@
+# @meissa_a/meissa
+
+Token-efficient generative UI for MCP, in one package with four entry points:
+
+| Import | What it is |
+| --- | --- |
+| `@meissa_a/meissa/renderer` | React component library — renders interactive UI from declarative JSON schemas |
+| `@meissa_a/meissa/client` | Client SDK for rendering Meissa content in MCP hosts (React) |
+| `@meissa_a/meissa/server` | Server SDK for returning Meissa UI from MCP tools (zero runtime deps) |
+| `@meissa_a/meissa/apps` | MCP Apps adapter — serves Meissa UI as sandboxed HTML iframes |
+
+Define your UI as compact tuples or objects, bind live data, and let the renderer handle the rest.
+
+## Installation
+
+```bash
+# npm
+npm install @meissa_a/meissa react react-dom
+
+# pnpm
+pnpm add @meissa_a/meissa react react-dom
+
+# bun
+bun add @meissa_a/meissa react react-dom
+```
+
+> `react` / `react-dom` are optional peers — only needed for the `renderer` and `client` entry points.
+
+### Requirements
+
+- React 19+
+- Tailwind CSS v4 (for styling)
+
+### Tailwind Setup
+
+Add the renderer's source to your Tailwind config so its classes are included:
+
+```css
+/* app.css */
+@import "tailwindcss";
+@source "../node_modules/@meissa_a/meissa/dist/**/*.js";
+```
+
+## Quick Start
+
+```tsx
+import { MeissaRenderer } from "@meissa_a/meissa/renderer";
+
+const schema = [
+  ["heading", "Hello World"],
+  ["text", "This is rendered from JSON."],
+  ["btn", { label: "Click me", action: "greet" }],
+];
+
+function App() {
+  return (
+    <MeissaRenderer
+      schema={schema}
+      data={{ user: "Alice" }}
+      onAction={(name, args) => console.log(name, args)}
+    />
+  );
+}
+```
+
+## API
+
+### `<MeissaRenderer>`
+
+The main entry point. Parses the schema, resolves data bindings, and renders the component tree.
+
+```tsx
+<MeissaRenderer
+  schema={schema}         // Meissa JSON schema (required)
+  data={data}             // Data context for {{bindings}}
+  theme={theme}           // Theme overrides
+  onAction={handler}      // Action callback (button clicks, form submits)
+  onNavigate={handler}    // Navigation callback
+  className="..."         // Container className
+/>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `schema` | `MeissaInput` | JSON schema — array of tuples, single node, or full document |
+| `data` | `Record<string, unknown>` | Data context for resolving `{{bindings}}` |
+| `theme` | `MeissaTheme` | Theme overrides (colors, radius, density, font) |
+| `onAction` | `(name: string, args?: Record<string, unknown>) => void` | Called when actions fire (button clicks, form submissions) |
+| `onNavigate` | `(uri: string) => void` | Called for navigation events |
+| `className` | `string` | CSS class on the container element |
+
+## Schema Format
+
+Schemas use a compact tuple syntax: `[type, primaryProp?, children?]`
+
+```json
+["text", "Hello"]
+["btn", { "label": "Submit", "variant": "primary" }]
+["row", { "gap": 4 }, [["btn", "A"], ["btn", "B"]]]
+```
+
+Or verbose object form:
+
+```json
+{ "type": "text", "content": "Hello", "bold": true }
+```
+
+### Full Document
+
+```json
+{
+  "v": 1,
+  "data": { "user": "Alice", "count": 42 },
+  "theme": { "radius": "md", "colors": { "primary": "#6366f1" } },
+  "ui": [
+    ["heading", "Dashboard"],
+    ["stat", { "label": "Users", "value": "{{count}}" }]
+  ]
+}
+```
+
+## Components
+
+22 built-in components covering layout, content, data display, and interactivity:
+
+### Layout
+
+| Component | Shorthand | Description |
+|-----------|-----------|-------------|
+| `row` | `["row", [children]]` | Horizontal flex container |
+| `col` | `["col", [children]]` | Vertical flex container |
+| `grid` | `["grid", { cols: 3 }, [children]]` | CSS grid |
+| `split` | `["split", { ratio: "1/3" }, [left, right]]` | Two-panel layout |
+| `divider` | `["divider"]` or `["divider", "Section"]` | Horizontal rule with optional label |
+
+### Content
+
+| Component | Shorthand | Description |
+|-----------|-----------|-------------|
+| `text` | `["text", "Hello"]` | Text content with variants |
+| `heading` | `["heading", "Title"]` | h1-h6 heading |
+| `code` | `["code", "const x = 1"]` | Code block or inline code |
+| `img` | `["img", "url"]` | Image |
+| `badge` | `["badge", "New"]` | Status indicator |
+| `alert` | `["alert", "Warning message"]` | Notification banner |
+| `progress` | `["progress", { value: 75 }]` | Progress bar |
+
+### Data Display
+
+| Component | Shorthand | Description |
+|-----------|-----------|-------------|
+| `stat` | `["stat", { label: "Revenue", value: "{{rev}}" }]` | KPI metric |
+| `list` | `["list", ["one", "two", "three"]]` | Ordered/unordered list |
+| `table` | `["table", { data: "{{rows}}" }]` | Data table with sorting & pagination |
+| `chart` | `["chart", { data: "{{sales}}", type: "bar" }]` | Recharts-powered chart |
+
+### Interactive
+
+| Component | Shorthand | Description |
+|-----------|-----------|-------------|
+| `btn` | `["btn", "Click me"]` | Button with action dispatch |
+| `input` | `["input", { name: "email", type: "email" }]` | Text input |
+| `select` | `["select", { name: "role", options: [...] }]` | Dropdown select |
+| `form` | `["form", { submit: "save" }, [children]]` | Form container |
+| `card` | `["card", "Title", [children]]` | Card container |
+| `tabs` | `["tabs", { items: {...} }]` | Tabbed panels |
+
+## Data Binding
+
+Use `{{path}}` syntax to bind data into any string prop:
+
+```json
+["text", "Hello, {{user.name}}!"]
+["stat", { "value": "{{metrics.revenue}}", "label": "Revenue" }]
+```
+
+### Filters
+
+Chain filters with `|`:
+
+```json
+["text", "{{price | currency}}"]
+["text", "{{name | uppercase}}"]
+["text", "{{description | truncate}}"]
+```
+
+Built-in filters: `currency`, `percent`, `number`, `uppercase`, `lowercase`, `truncate`, `relative`, `date`, `default`.
+
+### Comparisons
+
+Expressions resolve to booleans:
+
+```json
+["text", { "content": "Premium", "if": "{{plan == 'pro'}}" }]
+["alert", { "content": "Low stock", "if": "{{count < 10}}" }]
+```
+
+## Conditionals
+
+### `if` — Remove from DOM
+
+```json
+["text", { "content": "Admin only", "if": "{{isAdmin}}" }]
+```
+
+### `show` — Toggle visibility (keeps DOM element)
+
+```json
+["text", { "content": "Loading...", "show": "{{loading}}" }]
+```
+
+### `switch` — Multi-branch
+
+```json
+["switch", "{{status}}", {
+  "active": ["badge", { "content": "Active", "variant": "success" }],
+  "inactive": ["badge", { "content": "Inactive", "variant": "default" }],
+  "_": ["badge", "Unknown"]
+}]
+```
+
+## Iteration
+
+Loop over arrays with `each`:
+
+```json
+["each", "{{users}}", ["card", "{{$.name}}", [
+  ["text", "{{$.email}}"]
+]]]
+```
+
+Context variables inside each:
+- `$` — current item
+- `$i` — index (0-based)
+- `$first` — `true` for first item
+- `$last` — `true` for last item
+
+## Theming
+
+Pass a `theme` prop or include `theme` in the document:
+
+```tsx
+<MeissaRenderer
+  schema={schema}
+  theme={{
+    radius: "lg",
+    density: "relaxed",
+    font: "Inter, sans-serif",
+    colors: {
+      primary: "#6366f1",
+      destructive: "#ef4444",
+      success: "#10b981",
+      bg: "#ffffff",
+      fg: "#0f172a",
+      muted: "#64748b",
+      border: "#e2e8f0",
+    },
+  }}
+/>
+```
+
+## Actions
+
+Components dispatch actions via `onAction`:
+
+```tsx
+<MeissaRenderer
+  schema={[
+    ["btn", { "label": "Delete", "action": "deleteItem", "args": { "id": 42 } }],
+    ["form", { "submit": "saveUser" }, [
+      ["input", { "name": "email", "type": "email" }],
+      ["btn", { "label": "Save", "submit": true }]
+    ]]
+  ]}
+  onAction={(action, args) => {
+    // action: "deleteItem" | "saveUser"
+    // args: { id: 42 } | { email: "..." }
+  }}
+/>
+```
+
+## Advanced Usage
+
+### Custom Component Registry
+
+```tsx
+import { COMPONENT_REGISTRY, ComponentRenderer } from "@meissa_a/meissa/renderer";
+
+// Add a custom component
+COMPONENT_REGISTRY["my-widget"] = ({ node, children }) => (
+  <div className="my-widget">{children}</div>
+);
+```
+
+### Using Core Pipeline Directly
+
+```tsx
+import { parse, normalize, resolveBindings } from "@meissa_a/meissa/renderer";
+
+// Parse raw schema
+const doc = parse(rawJson);
+
+// Normalize a single tuple
+const node = normalize(["btn", { label: "Click", variant: "ghost" }]);
+
+// Resolve bindings manually
+const value = resolveBindings("{{user.name}}", { user: { name: "Alice" } });
+// → "Alice"
+```
+
+## TypeScript
+
+All types are exported:
+
+```tsx
+import type {
+  MeissaRendererProps,
+  MeissaInput,
+  MeissaDocument,
+  NormalizedNode,
+  MeissaTheme,
+  ComponentProps,
+  MeissaComponent,
+  ActionHandler,
+  NavigateHandler,
+} from "@meissa_a/meissa/renderer";
+```
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run tests
+bun test
+
+# Type check
+bun run typecheck
+
+# Build (ESM + CJS)
+bun run build
+
+# Watch mode
+bun run dev
+```
+
+## License
+
+MIT

package/dist/apps/app-generator.d.ts

@@ -0,0 +1,30 @@
+import type { MeissaSchema, MeissaAppOptions, MeissaAppResult } from "./types.js";
+/**
+ * Creates a self-contained Meissa app as an HTML string.
+ *
+ * This is the main entry point for the MCP Apps adapter. It takes a Meissa
+ * schema and options, and returns a complete HTML page that can be served
+ * as a sandboxed iframe resource in the MCP Apps protocol.
+ *
+ * @param schema - Meissa schema array describing the UI
+ * @param options - Optional configuration (theme, title, dimensions)
+ * @returns Object with `content` (HTML string) and `mimeType` ("text/html")
+ *
+ * @example
+ * ```typescript
+ * import { createMeissaApp } from "@meissa_a/meissa/apps";
+ *
+ * const result = createMeissaApp(
+ *   [
+ *     ["heading", "Dashboard"],
+ *     ["text", "Welcome, {{user.name}}!"],
+ *     ["btn", { label: "Refresh", action: "refresh" }],
+ *   ],
+ *   { title: "My Dashboard", theme: { primary: "#3b82f6" } }
+ * );
+ *
+ * // result.content -> complete HTML string
+ * // result.mimeType -> "text/html"
+ * ```
+ */
+export declare function createMeissaApp(schema: MeissaSchema, options?: MeissaAppOptions): MeissaAppResult;

package/dist/apps/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @meissa_a/meissa/apps
+ *
+ * MCP Apps adapter for serving Meissa UI as sandboxed HTML iframes.
+ *
+ * This package generates self-contained HTML pages that embed the Meissa
+ * renderer for use with the MCP Apps protocol. The generated HTML pages
+ * communicate with the host via postMessage.
+ *
+ * @example
+ * ```typescript
+ * import { createMeissaApp } from "@meissa_a/meissa/apps";
+ *
+ * // In an MCP server resource handler:
+ * const result = createMeissaApp(
+ *   [["heading", "Hello"], ["text", "World"]],
+ *   { title: "My App" }
+ * );
+ * // result.content is a complete HTML string
+ * // result.mimeType is "text/html"
+ * ```
+ */
+export { createMeissaApp } from "./app-generator.js";
+export type { MeissaSchema, MeissaSchemaElement, MeissaTheme, MeissaAppOptions, MeissaAppResult, MeissaOutgoingMessage, MeissaIncomingMessage, MeissaActionMessage, MeissaNavigateMessage, MeissaReadyMessage, MeissaResizeMessage, MeissaDataMessage, MeissaPatchMessage, MeissaUpdateMessage, MeissaActionResponseMessage, MeissaJsonPatch, } from "./types.js";
+export { MESSAGE_TYPES } from "./postmessage.js";

package/dist/apps/postmessage.d.ts

@@ -0,0 +1,24 @@
+/**
+ * PostMessage protocol definitions for Meissa MCP Apps.
+ *
+ * This module defines the message types and constants used for
+ * communication between the sandboxed iframe and the host application.
+ */
+/**
+ * Message type constants for the postMessage protocol.
+ */
+export declare const MESSAGE_TYPES: {
+    readonly ACTION: "meissa:action";
+    readonly NAVIGATE: "meissa:navigate";
+    readonly READY: "meissa:ready";
+    readonly RESIZE: "meissa:resize";
+    readonly DATA: "meissa:data";
+    readonly PATCH: "meissa:patch";
+    readonly UPDATE: "meissa:update";
+    readonly ACTION_RESPONSE: "meissa:action-response";
+};
+/**
+ * Returns the inline JavaScript code for the postMessage handler.
+ * This is injected into the HTML template.
+ */
+export declare function getPostMessageHandlerCode(): string;

package/dist/apps/template.d.ts

@@ -0,0 +1,10 @@
+import type { MeissaSchema, MeissaTheme } from "./types.js";
+/**
+ * Generate a complete self-contained HTML page from a Meissa schema.
+ */
+export declare function generateHtml(schema: MeissaSchema, options?: {
+    title?: string;
+    theme?: MeissaTheme;
+    width?: string;
+    height?: string;
+}): string;

package/dist/apps/types.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Meissa schema element — a tuple of [componentType, ...args]
+ * Examples:
+ *   ["heading", "Dashboard"]
+ *   ["btn", { label: "Click me", action: "onClick" }]
+ *   ["row", [...children]]
+ */
+export type MeissaSchemaElement = [string, ...unknown[]];
+/**
+ * A Meissa schema is an array of schema elements.
+ */
+export type MeissaSchema = MeissaSchemaElement[];
+/**
+ * Theme configuration for the Meissa renderer.
+ */
+export interface MeissaTheme {
+    /** Background color */
+    bg?: string;
+    /** Foreground/text color */
+    fg?: string;
+    /** Primary accent color */
+    primary?: string;
+    /** Secondary accent color */
+    secondary?: string;
+    /** Muted/subtle color */
+    muted?: string;
+    /** Border color */
+    border?: string;
+    /** Error/danger color */
+    error?: string;
+    /** Success color */
+    success?: string;
+    /** Warning color */
+    warning?: string;
+    /** Border radius (e.g., "0.5rem") */
+    radius?: string;
+    /** Font family */
+    font?: string;
+}
+/**
+ * Options for createMeissaApp.
+ */
+export interface MeissaAppOptions {
+    /** Theme configuration */
+    theme?: MeissaTheme;
+    /** HTML page title */
+    title?: string;
+    /** Width hint for iframe (e.g., "800px", "100%") */
+    width?: string;
+    /** Height hint for iframe (e.g., "600px", "100%") */
+    height?: string;
+}
+/**
+ * The result returned by createMeissaApp.
+ */
+export interface MeissaAppResult {
+    /** The complete self-contained HTML string */
+    content: string;
+    /** MIME type — always "text/html" */
+    mimeType: "text/html";
+}
+/**
+ * Outgoing messages (iframe -> host).
+ */
+export type MeissaOutgoingMessage = MeissaActionMessage | MeissaNavigateMessage | MeissaReadyMessage | MeissaResizeMessage;
+export interface MeissaActionMessage {
+    type: "meissa:action";
+    action: string;
+    args: Record<string, unknown>;
+}
+export interface MeissaNavigateMessage {
+    type: "meissa:navigate";
+    uri: string;
+}
+export interface MeissaReadyMessage {
+    type: "meissa:ready";
+}
+export interface MeissaResizeMessage {
+    type: "meissa:resize";
+    height: number;
+}
+/**
+ * Incoming messages (host -> iframe).
+ */
+export type MeissaIncomingMessage = MeissaDataMessage | MeissaPatchMessage | MeissaUpdateMessage | MeissaActionResponseMessage;
+export interface MeissaDataMessage {
+    type: "meissa:data";
+    data: Record<string, unknown>;
+}
+export interface MeissaPatchMessage {
+    type: "meissa:patch";
+    patches: MeissaJsonPatch[];
+}
+export interface MeissaUpdateMessage {
+    type: "meissa:update";
+    data: Record<string, unknown>;
+}
+export interface MeissaActionResponseMessage {
+    type: "meissa:action-response";
+    result: unknown;
+}
+export interface MeissaJsonPatch {
+    op: "add" | "remove" | "replace" | "move" | "copy" | "test";
+    path: string;
+    value?: unknown;
+    from?: string;
+}